feat: Add StableApi marker and API diff check#2168
Merged
Conversation
cbd01a5 to
e296cbd
Compare
e296cbd to
974e23a
Compare
Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
974e23a to
3431634
Compare
jaydeluca
approved these changes
Jun 1, 2026
| baseline_version: | ||
| description: Version to compare the PR artifacts against | ||
| required: false | ||
| default: "1.5.1" |
Collaborator
There was a problem hiding this comment.
how should we keep this up to date? should we create an issue to add a post-release step automation?
Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
zeitlinger
added a commit
that referenced
this pull request
Jun 2, 2026
…idiffs (#2174) ## Summary Fixes the manual-bump drift in the api-diff baseline (#2170) and makes API changes visible in review. - **Single source of truth.** The baseline lives only in the `<api.diff.baseline.version>` pom property (bumped from the already-drifted `1.5.1` to the actual latest release `1.6.1`). `mise.toml` and `api-diff.yml` no longer hardcode it. - **Renovate owns the bump.** A custom regex manager tracks the latest *published* `io.prometheus:prometheus-metrics-core` on Maven Central and bumps the property on the `renovate/api-diff-baseline` branch. Because Renovate only proposes published versions, there is no Maven Central propagation race and no post-release workflow or app token needed. - **Diffs committed to `docs/apidiffs/`.** `mise run api-diff` syncs the japicmp per-module reports into `docs/apidiffs/<module>.diff` via `.github/scripts/sync-api-diffs.sh`, stripping the volatile preamble so files only churn on real API changes. The api-diff workflow fails if they are stale, so every API change shows up in the PR diff. - **Regeneration on bump.** `generate-api-diff-baseline.yml` regenerates `docs/apidiffs` on the Renovate branch and pushes it back, mirroring `generate-protobuf.yml`. - `docs/apidiffs/**` is marked `linguist-generated` so flint skips it. ## Notes - The seed diffs are large because `1.6.1` predates `@StableApi` (the bootstrap noise documented in #2168). They shrink to near-empty once a release contains the annotations. - Like the protobuf flow, a `GITHUB_TOKEN` push doesn't re-trigger CI — close/reopen the Renovate bump PR to run the api-diff check after regeneration (noted in the workflow). ## Validation - `mise run api-diff` (generates the 25 seed diffs; verified idempotent) - `mise run lint` - `renovate-config-validator --strict`, actionlint, zizmor Closes #2170 ## Also fixes a pre-existing compat-test break on `main` `micrometer-compatibility` and `jmx-exporter-compatibility` fail on `main` (e.g. [#2173](#2173)), unrelated to this change. The compat harness installs local artifacts with `-Dmaven.test.skip=true`, which skips building the `*:test-jar` artifacts that the `activeByDefault` `default` profiles declare as test dependencies, breaking resolution (e.g. `prometheus-metrics-exposition-textformats:jar:tests`). Fixed by deactivating those profiles in the compat install (`-P !default`), matching what the release task already does (`-P release,!default`). Verified locally: full `mvnw install -Dmaven.test.skip=true -P !default` → BUILD SUCCESS. ## Reviewer note: the seed diffs show the full stable surface (expected) The committed `docs/apidiffs/current_vs_latest/*.txt` list the **entire** `@StableApi` surface as additions, not a small delta. This is the documented bootstrap state from #2168, not a bug: - The japicmp include filter is `@io.prometheus.metrics.annotations.StableApi`. The baseline `1.6.1` jar predates `@StableApi`, so its filtered surface is empty → every annotated class in current code registers as "NEW". The header genuinely compares against the `1.6.1` jar; the annotation filter is what makes everything look added. - Verified the filter is correct: only `@StableApi`-annotated types appear (non-stable classes like `CKMSQuantiles`/`Buffer` are excluded; `CallbackMetric` shows only as an inherited `NEW SUPERCLASS` reference). It is the same root cause as the `breaking-api-change-accepted` label on this PR. It self-corrects after the next release ships `@StableApi`: Renovate bumps the baseline to that release, the bump workflow regenerates `current_vs_latest/` as an annotated-vs-annotated (near-empty) diff, and the archived `<new>_vs_<old>/` becomes the first real release diff. So the current files are best read as a one-time record of the initial declared stable API surface. --------- Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
@StableApias the opt-in marker for published Java APImise run api-diffusing japicmp against the configured baselineNotes
This is the bootstrap PR for the annotation-based API surface. Since
1.5.1does not contain@StableApi, the first diff is noisy and mostly shows the seeded API surface as new. After arelease contains the annotations, future diffs should be normal compatibility diffs.
The workflow does not post PR comments or upload artifacts. If the check fails, run this locally:
Reports are written to
**/target/japicmp/*.Intentional incompatible changes can be accepted by adding the PR label
breaking-api-change-accepted.Validation
mise run api-diffmise run buildmise run lint